3D Graphics Programming with QuickDraw 3D 1.5.4
Previous | QD3D Book | Overview | Chapter Contents | Next |
Manipulating Draw Contexts
QuickDraw 3D RAVE provides routines that you can use to manipulate draw contexts. For example, you can use the QASetInt routine to set an integer-valued state variable associated with a draw context.
These functions are currently implemented as C language macros that call the methods of the drawing engine. Your application should use these macros for all draw context manipulation.
See the section "Application-Defined Routines" for complete information on the draw context methods invoked by these macros.
There is one macro for each method whose address is stored in a draw context structure (of type TQADrawContext ).
QAGetFloat
You can use the QAGetFloat function to get a floating-point value of a draw context state variable.
#define QAGetFloat(drawContext,tag) \
(drawContext)->getFloat (drawContext,tag)
QASetFloat
You can use the QASetFloat function to set a floating-point value for a draw context state variable.
#define QASetFloat(drawContext,tag,newValue) \
(drawContext)->setFloat (drawContext,tag,newValue)
QAGetInt
You can use the QAGetInt function to get a long integer value of a draw context state variable.
#define QAGetInt(drawContext,tag) \
(drawContext)->getInt (drawContext,tag)
QASetInt
You can use the QASetInt function to set a long integer value for a draw context state variable.
#define QASetInt(drawContext,tag,newValue) \
(drawContext)->setInt (drawContext,tag,newValue)
QAGetPtr
You can use the QAGetPtr function to get a pointer value of a draw context state variable.
#define QAGetPtr(drawContext,tag) \
(drawContext)->getPtr (drawContext,tag)
QASetPtr
You can use the QASetPtr function to set a pointer value for a draw context state variable.
#define QASetPtr(drawContext,tag,newValue) \
(drawContext)->setPtr (drawContext,tag,newValue)
QADrawPoint
You can use the QADrawPoint function to draw a point.
#define QADrawPoint(drawContext,v) \
(drawContext)->drawPoint (drawContext,v)
QADrawLine
You can use the QADrawLine function to draw a line between two points.
#define QADrawLine(drawContext,v0,v1) \
(drawContext)->drawLine (drawContext,v0,v1)
DESCRIPTION
The QADrawLine function draws the line specified by the v0 and v1 parameters to the draw context specified by the drawContext parameter. The size of the line is determined by the kQATag_Width state variable of the draw context. If the specified vertices have different colors, the line color is interpolated smoothly between the two vertex colors.
QADrawTriGouraud
You can use the QADrawTriGouraud function to draw Gouraud-shaded triangles.
#define QADrawTriGouraud(drawContext,v0,v1,v2,flags) \
(drawContext)->drawTriGouraud (drawContext,v0,v1,v2,flags)
- drawContext
- A draw context.
- v0
- A Gouraud vertex.
- v1
- A Gouraud vertex.
- v2
- A Gouraud vertex.
- flags
- A set of triangle flags. See "Triangle Flags Masks" for a complete description of the available flags.
DESCRIPTION
The QADrawTriGouraud function draws the Gouraud-shaded triangle determined by the three points specified by the v0 , v1 , and v2 parameters into the draw context specified by the drawContext parameter. Features of the triangle are determined by the flags parameter. Currently, this parameter is used to specify an orientation for the triangle.
QADrawTriTexture
You can use the QADrawTriTexture function to draw texture-mapped triangles.
#define QADrawTriTexture(drawContext,v0,v1,v2,flags) \
(drawContext)->drawTriTexture (drawContext,v0,v1,v2,flags)
- drawContext
- A draw context.
- v0
- A texture vertex.
- v1
- A texture vertex.
- v2
- A texture vertex.
- flags
- A set of triangle flags. See "Triangle Flags Masks" for a complete description of the available flags.
DESCRIPTION
The QADrawTriTexture function draws the texture-mapped triangle determined by the three points specified by the v0 , v1 , and v2 parameters into the draw context specified by the drawContext parameter. The texture used for the mapping is determined by the value of the kQATag_Texture state variable. Features of the triangle are determined by the flags parameter. Currently, this parameter is used to specify an orientation for the triangle.
QASubmitVerticesGouraud
You can use the QASubmitVerticesGouraud function to submit Gouraud vertices.
#define QASubmitVerticesGouraud(drawContext,nVertices,vertices) \
(drawContext)->submitVerticesGouraud(drawContext,nVertices,vertices)
- drawContext
- A draw context.
- nVertices
- The number of Gouraud vertices pointed to by the vertices parameter.
- vertices
- A pointer to an array of Gouraud vertices.
DESCRIPTION
The QASubmitVerticesGouraud function submits the list of vertices pointed to by the vertices parameter to the draw context specified by the drawContext parameter. The vertices define a triangle mesh. Note, however, that QASubmitVerticesGouraud does not draw the specified mesh, but simply defines the mesh for a subsequent call to QADrawTriMeshGouraud.
Your application is responsible for managing the memory occupied by the Gouraud vertices. QASubmitVerticesGouraud does not copy the vertex data pointed to by the vertices parameter. Accordingly, you must not dispose of or reuse that memory until you've finished drawing the triangle mesh defined by QASubmitVerticesGouraud .
QASubmitVerticesTexture
You can use the QASubmitVerticesTexture function to submit texture vertices.
#define QASubmitVerticesTexture(drawContext,nVertices,vertices) \
(drawContext)->submitVerticesTexture(drawContext,nVertices,vertices)
- drawContext
- A draw context.
- nVertices
- The number of texture vertices pointed to by the vertices parameter.
- vertices
- A pointer to an array of texture vertices.
DESCRIPTION
The QASubmitVerticesTexture function submits the list of vertices pointed to by the vertices parameter to the draw context specified by the drawContext parameter. The vertices define a triangle mesh. Note, however, that QASubmitVerticesTexture does not draw the specified mesh, but simply defines the mesh for a subsequent call to QADrawTriMeshTexture .
Your application is responsible for managing the memory occupied by the texture vertices. QASubmitVerticesTexture does not copy the vertex data pointed to by the vertices parameter. Accordingly, you must not dispose of or reuse that memory until you've finished drawing the triangle mesh defined by QASubmitVerticesTexture .
QADrawTriMeshGouraud
You can use the QADrawTriMeshGouraud function to draw a triangle mesh with Gouraud shading.
#define QADrawTriMeshGouraud(drawContext,nTriangle,triangles) \
(drawContext)->drawTriMeshGouraud (drawContext,nTriangle,triangles)
- drawContext
- A draw context.
- nTriangle
- The number of indexed triangles pointed to by the triangles parameter.
- triangles
- A pointer to an array of indexed triangles. See "Indexed Triangle Structure" for a description of indexed triangles.
DESCRIPTION
The QADrawTriMeshGouraud function draws, with Gouraud shading, the triangle mesh specified by the triangles parameter into the draw context specified by the drawContext parameter. Each triangle in the mesh is defined by a TQAIndexedTriangle data structure, which contains three indices into the array of Gouraud vertices previously submitted to the draw context by a call to the QASubmitVerticesGouraud function.
QADrawTriMeshTexture
You can use the QADrawTriMeshTexture function to draw a texture-mapped triangle mesh.
#define QADrawTriMeshTexture(drawContext,nTriangle,triangles) \
(drawContext)->drawTriMeshTexture (drawContext,nTriangle,triangles)
- drawContext
- A draw context.
- nTriangle
- The number of indexed triangles pointed to by the triangles parameter.
- triangles
- A pointer to an array of indexed triangles. See "Indexed Triangle Structure" for a description of indexed triangles.
DESCRIPTION
The QADrawTriMeshTexture function draws the texture-mapped triangle mesh specified by the triangles parameter into the draw context specified by the drawContext parameter. Each triangle in the mesh is defined by a TQAIndexedTriangle data structure, which contains three indices into the array of texture vertices previously submitted to the draw context by a call to the QASubmitVerticesTexture function.
SPECIAL CONSIDERATIONS
QADrawTriMeshTexture operates only on a triangle mesh previously submitted using the QASubmitVerticesTexture function. Use QADrawTriMeshGouraud to draw a triangle mesh submitted using the QASubmitVerticesGouraud function.
The QADrawTriMeshTexture function is optional and must be supported only by drawing engines that support texture mapping.
QADrawVGouraud
You can use the QADrawVGouraud function to draw Gouraud-shaded objects defined by vertices.
#define QADrawVGouraud(drawContext,nVertices,vertexMode,vertices,flags) \
(drawContext)->drawVGouraud(drawContext,nVertices,vertexMode,vertices,flags)
- drawContext
- A draw context.
- nVertices
- The number of vertices contained in the vertices array.
- vertexMode
- A vertex mode. See "Vertex Modes" for a description of the available vertex modes.
- vertices
- An array of Gouraud vertices.
- flags
- An array of triangle flags, or the value NULL . See "Triangle Flags Masks" for a description of the available triangle flags. This parameter is valid only if the vertexMode parameter contains the value kQAVertexMode_Tri , kQAVertexMode_Strip , or kQAVertexMode_Fan .
DESCRIPTION
The QADrawVGouraud function draws the vertices in the array specified by the vertices parameter into the draw context specified by the drawContext parameter, according to the vertex modes flag specified by the vertexMode parameter. For instance, if the value of the vertexMode parameter is kQAVertexMode_Polyline , then the vertices in that array are interpreted as defining a polyline (a set of connected line segments). Gouraud shading is applied to whatever objects are drawn.
QADrawVTexture
You can use the QADrawVTexture function to draw texture-mapped objects defined by vertices.
#define QADrawVTexture(drawContext,nVertices,vertexMode,vertices,flags) \
(drawContext)->drawVTexture(drawContext,nVertices,vertexMode,vertices,flags)
- drawContext
- A draw context.
- nVertices
- The number of vertices contained in the vertices array.
- vertexMode
- A vertex mode. See "Vertex Modes" for a description of the available vertex modes.
- vertices
- An array of texture vertices.
- flags
- An array of triangle flags, or the value NULL . See "Triangle Flags Masks" for a description of the available triangle flags. This parameter is valid only if the vertexMode parameter contains the value kQAVertexMode_Tri , kQAVertexMode_Strip , or kQAVertexMode_Fan .
DESCRIPTION
The QADrawVTexture function draws the vertices in the array specified by the vertices parameter into the draw context specified by the drawContext parameter, according to the vertex modes flag specified by the vertexMode parameter. For instance, if the value of the vertexMode parameter is kQAVertexMode_Polyline , then the vertices in that array are interpreted as defining a polyline (a set of connected line segments). Texture mapping (using the texture determined by the value of the kQATag_Texture state variable) is applied to whatever objects are drawn.
The vertex modes kQAVertexMode_Point and kQAVertexMode_Line are supported only by drawing engines that support the kQAOptional_OpenGL feature. All other drawing engines should ignore requests to texture map points or lines.
QADrawBitmap
You can use the QADrawBitmap function to draw bitmaps into a draw context.
#define QADrawBitmap(drawContext,v,bitmap) \
(drawContext)->drawBitmap (drawContext,v,bitmap)
- drawContext
- A draw context.
- v
- A Gouraud vertex.
- bitmap
- A pointer to a bitmap (returned by a previous call to QABitmapNew ).
DESCRIPTION
The QADrawBitmap function draws the bitmap specified by the bitmap parameter into the draw context specified by the drawContext parameter, with the upper-left corner of the bitmap located at the point specified by the v parameter. The v parameter can contain negative values in its x or y fields, so you can position upper-left corner of the bitmap outside the draw context rectangle. This allows you to move the bitmap smoothly off any edge of the draw context.
QARenderStart
You can use the QARenderStart function to initialize a draw context before an engine performs any rendering into that context.
#define QARenderStart(drawContext,dirtyRect,initialContext) \
(drawContext)->renderStart (drawContext,dirtyRect,initialContext)
- drawContext
- A draw context.
- dirtyRect
- The minimum area of the specified draw context to clear, or the value NULL .
- initialContext
- A previously cached draw context, or the value NULL .
DESCRIPTION
The QARenderStart function performs any operations necessary to initialize the draw context specified by the drawContext parameter. This includes clearing the z buffer and the color buffers of the draw context. If the value of the initialContext parameter is NULL , then QARenderStart clears the z buffer to 1.0 and sets the color buffers to the values of the kQATag_ColorBG_a , kQATag_ColorBG_r , kQATag_ColorBG_g , and kQATag_ColorBG_b draw context state variables. If, however, the value of the initialContext parameter is not NULL , then QARenderStart uses the previously cached draw context specified by that parameter to initialize the draw context specified by the drawContext parameter.
The dirtyRect parameter indicates the minimum area, in local coordinates of the draw context, of the specified draw context to clear on initialization. If the value of the dirtyRect parameter is NULL , the entire draw context is cleared. If the value of the dirtyRect parameter is not NULL , it indicates the rectangle in the draw context to clear. Some drawing engines may exhibit improved performance when an area that is smaller than the entire draw context rectangle is passed. However, the interpretation of the dirtyRect parameter is dependent on the drawing engine, which may choose to initialize the entire draw context. As a result, you should not use this parameter as a means to avoid clearing all of a draw context or to perform incremental rendering. Instead, you should use the initialContext parameter to achieve such effects.
SPECIAL CONSIDERATIONS
You should call QARenderStart before performing any rendering operations in the specified draw context, and you should call either QARenderEnd to signal the end of rendering operations or QARenderAbort to cancel rendering operations. However, when a drawing engine is performing OpenGL rendering, the QARenderStart function operates just like the OpenGL function glClear . In OpenGL mode, it is not necessary that a call to QARenderStart always be balanced by a matching call to QARenderEnd , and drawing commands may occur at any time.
SEE ALSO
See "Using a Draw Context as a Cache" for information on creating a draw context cache (that is, a draw context you can use as the initial context specified in the initialContext parameter).
QARenderEnd
You can use the QARenderEnd function to signal the end of any rendering into a draw context.
#define QARenderEnd(drawContext,modifiedRect) \
(drawContext)->renderEnd (drawContext,modifiedRect)
- drawContext
- A draw context.
- modifiedRect
- The minimum area of the back buffer of the specified draw context to display, or the value NULL .
DESCRIPTION
The QARenderEnd function performs any operations necessary to display an image rendered into the draw context specified by the drawContext parameter. If the draw context is double buffered, QARenderEnd displays the back buffer. If the draw context is single buffered, QARenderEnd calls QAFlush .
The modifiedRect parameter indicates the minimum area of the back buffer of the specified draw context that should be displayed. If the value of the modifiedRect parameter is NULL , the entire back buffer is displayed. If the value of the modifiedRect parameter is not NULL , it indicates the rectangle in the back buffer to display. Some drawing engines may exhibit improved performance when an area that is smaller than the entire draw context rectangle is passed (to avoid unnecessary pixel copying). However, the interpretation of the modifiedRect parameter is dependent on the drawing engine, which may choose to draw the entire back buffer.
The QARenderEnd function returns a result code (of type TQAError ) indicating whether any errors have occurred since the previous call to QARenderStart . If all rendering commands completed successfully, the value kQANoErr is returned. If any other value is returned, you should assume that the rendered image is incorrect.
SPECIAL CONSIDERATIONS
You should call QARenderStart before performing any rendering operations in the specified draw context, and you should call either QARenderEnd to signal the end of rendering operations or QARenderAbort to cancel rendering operations. Once you have called QARenderEnd , you should not submit any drawing requests until you have called QARenderStart again.
QARenderAbort
You can use the QARenderAbort function to cancel any asynchronous drawing requests for a draw context.
#define QARenderAbort(drawContext) \
(drawContext)->renderAbort (drawContext)
DESCRIPTION
The QARenderAbort function immediately stops the draw context specified by the drawContext parameter from processing any asynchronous drawing commands it is currently processing and causes it to discard any queued commands.
The QARenderAbort function returns a result code (of type TQAError ) indicating whether any errors have occurred since the previous call to QARenderStart . If all rendering commands completed successfully, the value kQANoErr is returned. If any other value is returned, you should assume that the rendered image is incorrect.
QAFlush
You can use the QAFlush function to flush a draw context.
#define QAFlush(drawContext) (drawContext)->flush (drawContext)
DESCRIPTION
The QAFlush function causes the drawing engine associated with the draw context specified by the drawContext parameter to begin rendering all drawing commands that are queued in a buffer awaiting processing. QuickDraw 3D RAVE allows a drawing engine to buffer as many drawing commands as desired. Accordingly, the successful completion of a drawing command (such as QADrawPoint ) does not guarantee that the specified object is visible on the screen. You can call QAFlush to have a drawing engine start processing queued commands. Note, however, that QAFlush is not a blocking call--that is, the successful completion of QAFlush does not guarantee that all buffered commands have been processed. Calling QAFlush guarantees only that all queued commands will eventually be processed.
Typically, you should occasionally call QAFlush to update the screen image during a lengthy set of rendering operations in a single-buffered draw context. QAFlush has no visible effect when called on a double-buffered draw context, but it does initiate rendering to the back buffer.
The TQAFlush function returns a result code (of type TQAError ) indicating whether any errors have occurred since the previous call to QARenderStart . If all rendering commands completed successfully, the value kQANoErr is returned. If any other value is returned, you should assume that the rendered image is incorrect.
QASync
You can use the QASync function to synchronize a draw context.
#define QASync(drawContext) (drawContext)->sync (drawContext)
DESCRIPTION
The QASync function operates just like the QAFlush function, except that it waits until all queued drawing commands have been processed before returning. See the description of QAFlush [link] for complete details.
QAGetNoticeMethod
You can use the QAGetNoticeMethod function to get the notice method of a draw context.
#define QAGetNoticeMethod(drawContext, method, completionCallBack, refCon) \
(drawContext)->getNoticeMethod (drawContext, method, completionCallBack, refCon)
- drawContext
- A draw context.
- method
- A method selector. See "Notice Method Selectors" for a description of the available method selectors.
- completionCallBack
- On exit, a pointer to the current draw context notice method of the specified type.
- refCon
- On exit, the reference constant of the specified notice method.
DESCRIPTION
The QAGetNoticeMethod function returns, in the completionCallBack parameter, a pointer to the current notice method of the draw context specified by the drawContext parameter that has the type specified by the method parameter. QAGetNoticeMethod also returns, in the refCon parameter, the reference constant associated with that notice method.
QASetNoticeMethod
You can use the QASetNoticeMethod function to set the notice method of a draw context.
#define QASetNoticeMethod(drawContext, method, completionCallBack, refCon) \
(drawContext)->setNoticeMethod (drawContext, method, completionCallBack, refCon)
- drawContext
- A draw context.
- method
- A method selector. See "Notice Method Selectors" for a description of the available method selectors.
- completionCallBack
- A pointer to the desired draw context notice method of the specified type. See "Notice Methods" for information about notice methods.
- refCon
- A reference constant for the specified notice method. This value is passed unchanged to the notice method when it is called.
DESCRIPTION
The QASetNoticeMethod function sets the notice method of type method of the draw context specified by the drawContext parameter to the function pointed to by the completionCallBack parameter. QASetNoticeMethod also sets the reference constant of that method to the value specified by the refCon parameter.
© 1997 Apple Computer, Inc.
Previous | QD3D Book | Overview | Chapter Contents | Next |